home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK2.toast / Development Kits / QuickTime / QuickTime 3 Interfaces & Libs / QTDevWin / CIncludes / AppleGuide.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-21  |  13.8 KB  |  516 lines  |  [TEXT/dosa]
  1. /*
  2.      File:        AppleGuide.h
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    QuickTime 3.0
  8.  
  9.      Copyright:    ©1994-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __APPLEGUIDE__
  19. #define __APPLEGUIDE__
  20.  
  21. #ifndef __MACTYPES__
  22. #include <MacTypes.h>
  23. #endif
  24. #ifndef __APPLEEVENTS__
  25. #include <AppleEvents.h>
  26. #endif
  27. #ifndef __FILES__
  28. #include <Files.h>
  29. #endif
  30.  
  31.  
  32.  
  33.  
  34. #if PRAGMA_ONCE
  35. #pragma once
  36. #endif
  37.  
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41.  
  42. #if PRAGMA_IMPORT
  43. #pragma import on
  44. #endif
  45.  
  46. #if PRAGMA_STRUCT_ALIGN
  47.     #pragma options align=mac68k
  48. #elif PRAGMA_STRUCT_PACKPUSH
  49.     #pragma pack(push, 2)
  50. #elif PRAGMA_STRUCT_PACK
  51.     #pragma pack(2)
  52. #endif
  53.  
  54. /* Types*/
  55. typedef UInt32                             AGRefNum;
  56. typedef UInt32                             AGCoachRefNum;
  57. typedef UInt32                             AGContextRefNum;
  58.  
  59. struct AGAppInfo {
  60.     AEEventID                         eventId;
  61.     long                             refCon;
  62.     void *                            contextObj;                    /* private system field*/
  63. };
  64. typedef struct AGAppInfo                AGAppInfo;
  65. typedef AGAppInfo *                        AGAppInfoPtr;
  66. typedef AGAppInfoPtr *                    AGAppInfoHdl;
  67. typedef CALLBACK_API( OSErr , CoachReplyProcPtr )(Rect *pRect, Ptr name, long refCon);
  68. typedef CALLBACK_API( OSErr , ContextReplyProcPtr )(Ptr pInputData, Size inputDataSize, Ptr *ppOutputData, Size *pOutputDataSize, AGAppInfoHdl hAppInfo);
  69. typedef STACK_UPP_TYPE(CoachReplyProcPtr)                         CoachReplyUPP;
  70. typedef STACK_UPP_TYPE(ContextReplyProcPtr)                     ContextReplyUPP;
  71. enum { uppCoachReplyProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  72. enum { uppContextReplyProcInfo = 0x0000FFE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  73. #define NewCoachReplyProc(userRoutine)                             (CoachReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppCoachReplyProcInfo, GetCurrentArchitecture())
  74. #define NewContextReplyProc(userRoutine)                         (ContextReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppContextReplyProcInfo, GetCurrentArchitecture())
  75. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)     CALL_THREE_PARAMETER_UPP((userRoutine), uppCoachReplyProcInfo, (pRect), (name), (refCon))
  76. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo)  CALL_FIVE_PARAMETER_UPP((userRoutine), uppContextReplyProcInfo, (pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  77. /* Constants*/
  78.  
  79.  
  80.  
  81. enum {
  82.     kAGDefault                    = 0,
  83.     kAGFrontDatabase            = 1,
  84.     kAGNoMixin                    = (-1)
  85. };
  86.  
  87.  
  88.  
  89. enum {
  90.     kAGViewFullHowdy            = 1,                            /* Full-size Howdy*/
  91.     kAGViewTopicAreas            = 2,                            /* Full-size Topic Areas*/
  92.     kAGViewIndex                = 3,                            /* Full-size Index Terms*/
  93.     kAGViewLookFor                = 4,                            /* Full-size Look-For (Search)*/
  94.     kAGViewSingleHowdy            = 5,                            /* Single-list-size Howdy*/
  95.     kAGViewSingleTopics            = 6                                /* Single-list-size Topics*/
  96. };
  97.  
  98.  
  99.  
  100. enum {
  101.     kAGFileMain                    = FOUR_CHAR_CODE('poco'),
  102.     kAGFileMixin                = FOUR_CHAR_CODE('mixn')
  103. };
  104.  
  105. /* To test against AGGetAvailableDBTypes*/
  106.  
  107. enum {
  108.     kAGDBTypeBitAny                = 0x00000001,
  109.     kAGDBTypeBitHelp            = 0x00000002,
  110.     kAGDBTypeBitTutorial        = 0x00000004,
  111.     kAGDBTypeBitShortcuts        = 0x00000008,
  112.     kAGDBTypeBitAbout            = 0x00000010,
  113.     kAGDBTypeBitOther            = 0x00000080
  114. };
  115.  
  116.  
  117.  
  118. typedef UInt16                             AGStatus;
  119. /* Returned by AGGetStatus*/
  120.  
  121. enum {
  122.     kAGIsNotRunning                = 0,
  123.     kAGIsSleeping                = 1,
  124.     kAGIsActive                    = 2
  125. };
  126.  
  127.  
  128. typedef UInt16                             AGWindowKind;
  129. /* Returned by AGGetFrontWindowKind*/
  130.  
  131. enum {
  132.     kAGNoWindow                    = 0,
  133.     kAGAccessWindow                = 1,
  134.     kAGPresentationWindow        = 2
  135. };
  136.  
  137. /* Error Codes*/
  138.  
  139. /* Not an enum, because other OSErrs are valid.*/
  140. typedef SInt16                             AGErr;
  141. /* Apple Guide error codes*/
  142.  
  143. enum {
  144.                                                                 /* -------------------- Apple event reply codes*/
  145.     kAGErrUnknownEvent            = -2900,
  146.     kAGErrCantStartup            = -2901,
  147.     kAGErrNoAccWin                = -2902,
  148.     kAGErrNoPreWin                = -2903,
  149.     kAGErrNoSequence            = -2904,
  150.     kAGErrNotOopsSequence        = -2905,
  151.     kAGErrReserved06            = -2906,
  152.     kAGErrNoPanel                = -2907,
  153.     kAGErrContentNotFound        = -2908,
  154.     kAGErrMissingString            = -2909,
  155.     kAGErrInfoNotAvail            = -2910,
  156.     kAGErrEventNotAvailable        = -2911,
  157.     kAGErrCannotMakeCoach        = -2912,
  158.     kAGErrSessionIDsNotMatch    = -2913,
  159.     kAGErrMissingDatabaseSpec    = -2914,                        /* -------------------- Coach's Chalkboard reply codes*/
  160.     kAGErrItemNotFound            = -2925,
  161.     kAGErrBalloonResourceNotFound = -2926,
  162.     kAGErrChalkResourceNotFound    = -2927,
  163.     kAGErrChdvResourceNotFound    = -2928,
  164.     kAGErrAlreadyShowing        = -2929,
  165.     kAGErrBalloonResourceSkip    = -2930,
  166.     kAGErrItemNotVisible        = -2931,
  167.     kAGErrReserved32            = -2932,
  168.     kAGErrNotFrontProcess        = -2933,
  169.     kAGErrMacroResourceNotFound    = -2934,                        /* -------------------- API reply codes*/
  170.     kAGErrAppleGuideNotAvailable = -2951,
  171.     kAGErrCannotInitCoach        = -2952,
  172.     kAGErrCannotInitContext        = -2953,
  173.     kAGErrCannotOpenAliasFile    = -2954,
  174.     kAGErrNoAliasResource        = -2955,
  175.     kAGErrDatabaseNotAvailable    = -2956,
  176.     kAGErrDatabaseNotOpen        = -2957,
  177.     kAGErrMissingAppInfoHdl        = -2958,
  178.     kAGErrMissingContextObject    = -2959,
  179.     kAGErrInvalidRefNum            = -2960,
  180.     kAGErrDatabaseOpen            = -2961,
  181.     kAGErrInsufficientMemory    = -2962
  182. };
  183.  
  184. /* Events*/
  185.  
  186. /* Not an enum because we want to make assignments.*/
  187. typedef UInt32                             AGEvent;
  188. /* Handy events for AGGeneral.*/
  189.  
  190. enum {
  191.                                                                 /* Panel actions (Require a presentation window).*/
  192.     kAGEventDoCoach                = FOUR_CHAR_CODE('doco'),
  193.     kAGEventDoHuh                = FOUR_CHAR_CODE('dhuh'),
  194.     kAGEventGoNext                = FOUR_CHAR_CODE('gonp'),
  195.     kAGEventGoPrev                = FOUR_CHAR_CODE('gopp'),
  196.     kAGEventHidePanel            = FOUR_CHAR_CODE('pahi'),
  197.     kAGEventReturnBack            = FOUR_CHAR_CODE('gobk'),
  198.     kAGEventShowPanel            = FOUR_CHAR_CODE('pash'),
  199.     kAGEventTogglePanel            = FOUR_CHAR_CODE('patg')
  200. };
  201.  
  202. /* Functions*/
  203.  
  204. /*
  205.    AGClose
  206.    Close the database associated with the AGRefNum.
  207. */
  208.  
  209. EXTERN_API( AGErr )
  210. AGClose                            (AGRefNum *                refNum)                                TWOWORDINLINE(0x7011, 0xAA6E);
  211.  
  212. /*
  213.    AGGeneral
  214.    Cause various events to happen.
  215. */
  216.  
  217. EXTERN_API( AGErr )
  218. AGGeneral                        (AGRefNum                 refNum,
  219.                                  AGEvent                 theEvent)                            TWOWORDINLINE(0x700D, 0xAA6E);
  220.  
  221. /*
  222.    AGGetAvailableDBTypes
  223.    Return the database types available for this application.
  224. */
  225.  
  226. EXTERN_API( UInt32 )
  227. AGGetAvailableDBTypes            (void)                                                        TWOWORDINLINE(0x7008, 0xAA6E);
  228.  
  229. /*
  230.    AGGetFrontWindowKind
  231.    Return the kind of the front window.
  232. */
  233.  
  234. EXTERN_API( AGWindowKind )
  235. AGGetFrontWindowKind            (AGRefNum                 refNum)                                TWOWORDINLINE(0x700C, 0xAA6E);
  236.  
  237. /*
  238.    AGGetFSSpec
  239.    Return the FSSpec for the AGRefNum.
  240. */
  241.  
  242. EXTERN_API( AGErr )
  243. AGGetFSSpec                        (AGRefNum                 refNum,
  244.                                  FSSpec *                fileSpec)                            TWOWORDINLINE(0x700F, 0xAA6E);
  245.  
  246. /*
  247.    AGGetStatus
  248.    Return the status of Apple Guide.
  249. */
  250.  
  251. EXTERN_API( AGStatus )
  252. AGGetStatus                        (void)                                                        TWOWORDINLINE(0x7009, 0xAA6E);
  253.  
  254. /*
  255.    AGInstallCoachHandler
  256.    Install a Coach object location query handler.
  257. */
  258.  
  259. EXTERN_API( AGErr )
  260. AGInstallCoachHandler            (CoachReplyUPP             coachReplyProc,
  261.                                  long                     refCon,
  262.                                  AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7012, 0xAA6E);
  263.  
  264. /*
  265.    AGInstallContextHandler
  266.    Install a context check query handler.
  267. */
  268.  
  269. EXTERN_API( AGErr )
  270. AGInstallContextHandler            (ContextReplyUPP         contextReplyProc,
  271.                                  AEEventID                 eventID,
  272.                                  long                     refCon,
  273.                                  AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7013, 0xAA6E);
  274.  
  275. /*
  276.    AGIsDatabaseOpen
  277.    Return true if the database associated with the AGRefNum is open.
  278. */
  279.  
  280. EXTERN_API( Boolean )
  281. AGIsDatabaseOpen                (AGRefNum                 refNum)                                TWOWORDINLINE(0x7006, 0xAA6E);
  282.  
  283. /*
  284.    AGOpen
  285.    Open a guide database.
  286. */
  287.  
  288. EXTERN_API( AGErr )
  289. AGOpen                            (ConstFSSpecPtr         fileSpec,
  290.                                  UInt32                 flags,
  291.                                  Handle                 mixinControl,
  292.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7001, 0xAA6E);
  293.  
  294. /*
  295.    AGOpenWithSearch
  296.    Open a guide database and preset a search string.
  297. */
  298.  
  299. EXTERN_API( AGErr )
  300. AGOpenWithSearch                (ConstFSSpecPtr         fileSpec,
  301.                                  UInt32                 flags,
  302.                                  Handle                 mixinControl,
  303.                                  ConstStr255Param         searchString,
  304.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7002, 0xAA6E);
  305.  
  306. /*
  307.    AGOpenWithSequence
  308.    Open a guide database and display a presentation window sequence.
  309. */
  310.  
  311. EXTERN_API( AGErr )
  312. AGOpenWithSequence                (ConstFSSpecPtr         fileSpec,
  313.                                  UInt32                 flags,
  314.                                  Handle                 mixinControl,
  315.                                  short                     sequenceID,
  316.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7004, 0xAA6E);
  317.  
  318. /*
  319.    AGOpenWithView
  320.    Open a guide database and override the default view.
  321. */
  322.  
  323. EXTERN_API( AGErr )
  324. AGOpenWithView                    (ConstFSSpecPtr         fileSpec,
  325.                                  UInt32                 flags,
  326.                                  Handle                 mixinControl,
  327.                                  short                     viewNum,
  328.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7005, 0xAA6E);
  329.  
  330. /*
  331.    AGQuit
  332.    Make Apple Guide quit.
  333. */
  334.  
  335. EXTERN_API( AGErr )
  336. AGQuit                            (void)                                                        TWOWORDINLINE(0x7010, 0xAA6E);
  337.  
  338. /*
  339.    AGRemoveCoachHandler
  340.    Remove the Coach object location query handler.
  341. */
  342.  
  343. EXTERN_API( AGErr )
  344. AGRemoveCoachHandler            (AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7014, 0xAA6E);
  345.  
  346. /*
  347.    AGRemoveContextHandler
  348.    Remove the context check query handler.
  349. */
  350.  
  351. EXTERN_API( AGErr )
  352. AGRemoveContextHandler            (AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7015, 0xAA6E);
  353.  
  354. /*
  355.    AGStart
  356.    Start up Apple Guide in the background.
  357. */
  358.  
  359. EXTERN_API( AGErr )
  360. AGStart                            (void)                                                        TWOWORDINLINE(0x700A, 0xAA6E);
  361.  
  362.  
  363.  
  364. /* typedef's*/
  365.  
  366. typedef FSSpec                             AGFileFSSpecType;
  367. typedef short                             AGFileSelectorCountType;
  368. typedef short                             AGFileSelectorIndexType;
  369. typedef OSType                             AGFileSelectorType;
  370. typedef long                             AGFileSelectorValueType;
  371. typedef short                             AGFileDBType;
  372. typedef Str63                             AGFileDBMenuNamePtr;
  373. typedef short                             AGFileDBScriptType;
  374. typedef short                             AGFileDBRegionType;
  375. typedef short                             AGFileMajorRevType;
  376. typedef short                             AGFileMinorRevType;
  377. typedef short                             AGFileCountType;
  378. /* Database types (for AGFileDBType parameter).*/
  379.  
  380. enum {
  381.     kAGFileDBTypeAny            = 0,
  382.     kAGFileDBTypeHelp            = 1,
  383.     kAGFileDBTypeTutorial        = 2,
  384.     kAGFileDBTypeShortcuts        = 3,
  385.     kAGFileDBTypeAbout            = 4,
  386.     kAGFileDBTypeOther            = 8
  387. };
  388.  
  389.  
  390.  
  391. EXTERN_API( OSErr )
  392. AGFileGetDBMenuName                (const FSSpec *            fileSpec,
  393.                                  Str63                     menuItemNameString);
  394.  
  395. /* Get the database type.*/
  396. EXTERN_API( OSErr )
  397. AGFileGetDBType                    (const FSSpec *            fileSpec,
  398.                                  AGFileDBType *            databaseType);
  399.  
  400. /*
  401.    Get the version of the software
  402.    that created this database.
  403. */
  404. EXTERN_API( OSErr )
  405. AGFileGetDBVersion                (const FSSpec *            fileSpec,
  406.                                  AGFileMajorRevType *    majorRev,
  407.                                  AGFileMinorRevType *    minorRev);
  408.  
  409. /* Get the database script and region information.*/
  410. EXTERN_API( OSErr )
  411. AGFileGetDBCountry                (const FSSpec *            fileSpec,
  412.                                  AGFileDBScriptType *    script,
  413.                                  AGFileDBRegionType *    region);
  414.  
  415. /* Return the number of selectors in database.*/
  416. EXTERN_API( AGFileSelectorCountType )
  417. AGFileGetSelectorCount            (const FSSpec *            fileSpec);
  418.  
  419. /*
  420.    Get the i-th database selector (1 to AGFileSelectorCountType)
  421.    and its value.
  422. */
  423. EXTERN_API( OSErr )
  424. AGFileGetSelector                (const FSSpec *            fileSpec,
  425.                                  AGFileSelectorIndexType  selectorNumber,
  426.                                  AGFileSelectorType *    selector,
  427.                                  AGFileSelectorValueType * value);
  428.  
  429. /* Return true if database is mixin.*/
  430. EXTERN_API( Boolean )
  431. AGFileIsMixin                    (const FSSpec *            fileSpec);
  432.  
  433. /*
  434.    Return the number of database files
  435.    of the specified databaseType and main/mixin.
  436.    Any file creator is acceptible,
  437.    but type must be kAGFileMain or kAGFileMixin.
  438. */
  439. EXTERN_API( AGFileCountType )
  440. AGFileGetDBCount                (short                     vRefNum,
  441.                                  long                     dirID,
  442.                                  AGFileDBType             databaseType,
  443.                                  Boolean                 wantMixin);
  444.  
  445. /*
  446.    Get the FSSpec for the dbIndex-th database
  447.    of the specified databaseType and main/mixin.
  448.    Any file creator is acceptible,
  449.    but type must be kAGFileMain or kAGFileMixin.
  450. */
  451. EXTERN_API( OSErr )
  452. AGFileGetIndDB                    (short                     vRefNum,
  453.                                  long                     dirID,
  454.                                  AGFileDBType             databaseType,
  455.                                  Boolean                 wantMixin,
  456.                                  short                     dbIndex,
  457.                                  FSSpec *                fileSpec);
  458.  
  459. /*
  460.    This selector must match with the application
  461.    creator in order for this file to appear in the 
  462.    application's Help menu. Ignored for mixin files
  463.    because they never appear in the Help menu anyway.
  464.    If empty (zeros), will appear in the Help menu
  465.    of any host application.
  466. */
  467. EXTERN_API( OSErr )
  468. AGFileGetHelpMenuAppCreator        (const FSSpec *            fileSpec,
  469.                                  OSType *                helpMenuAppCreator);
  470.  
  471. /*
  472.    This selector must match in the main and mixin
  473.    files in order for the mixin to mix-in with the main.
  474.    Empty (zeros) selectors are valid matches.
  475.    A '****' selector will mix-in with any main.
  476. */
  477. EXTERN_API( OSErr )
  478. AGFileGetMixinMatchSelector        (const FSSpec *            fileSpec,
  479.                                  OSType *                mixinMatchSelector);
  480.  
  481. /*
  482.    This is the text of the balloon for the
  483.    Help menu item for this database.
  484. */
  485. EXTERN_API( OSErr )
  486. AGFileGetHelpMenuBalloonText    (const FSSpec *            fileSpec,
  487.                                  Str255                 helpMenuBalloonString);
  488.  
  489.  
  490. EXTERN_API( OSErr )
  491. AGGetSystemDB                    (AGFileDBType             databaseType,
  492.                                  Boolean                 wantMixin,
  493.                                  FSSpec *                pFileSpec);
  494.  
  495.  
  496. #if PRAGMA_STRUCT_ALIGN
  497.     #pragma options align=reset
  498. #elif PRAGMA_STRUCT_PACKPUSH
  499.     #pragma pack(pop)
  500. #elif PRAGMA_STRUCT_PACK
  501.     #pragma pack()
  502. #endif
  503.  
  504. #ifdef PRAGMA_IMPORT_OFF
  505. #pragma import off
  506. #elif PRAGMA_IMPORT
  507. #pragma import reset
  508. #endif
  509.  
  510. #ifdef __cplusplus
  511. }
  512. #endif
  513.  
  514. #endif /* __APPLEGUIDE__ */
  515.  
  516.